home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / rjcom.exe / COM.TXT < prev    next >
Text File  |  1991-12-14  |  59KB  |  2,043 lines
  1.  
  2.  
  3.  
  4.         
  5.         
  6.                              COM.LIB communications
  7.         
  8.         
  9.         The functions described in this document allow a C program to set 
  10.         up  and control communications that will take place  through  the 
  11.         serial  ports.  The routines are found in the  library  COM_S.LIB 
  12.         for  small model or COM_L for the large C model. The  initializa-
  13.         tion  function sets up an ISR that handles  communications.   The 
  14.         ISR  takes  the place of INT-14 and supports up  to  four  serial 
  15.         interfaces.  COM.LIB supports both IRQ-3 and IRQ-4  for  transmit 
  16.         and receive and also supports other enhanced commands for the COM 
  17.         ports.  In addition to this file, INT_14.H is a header file  that 
  18.         must  be  included.  It contains the  necessary  definitions  for 
  19.         communication  port  data  transfers done with  this  library  of 
  20.         routines.
  21.         
  22.         INT_14.H  specify  four typedefs that will  be  used  extensively 
  23.         throughout this document.  They are as follows:
  24.         
  25.              typedef unsigned char    uc;
  26.              typedef unsigned int     ui;
  27.              typedef unsigned long    ul;
  28.              typedef unsigned short   us;
  29.         
  30.         These storage classes have been defined in this manner to facili-
  31.         tate  casting  operations and to eliminate keystrokes  in  normal 
  32.         declarations.
  33.         
  34.         It should be noted that the variable cn, used extensively in  the 
  35.         following  definitions  to symbolize the com_number,  is  of  the 
  36.         following format:
  37.                ( COM1 = 0, COM2 = 1, COM3 = 2, COM4 = 3, etc... )
  38.         
  39.         There are several shorthand notations used in this document.
  40.         They are listed here:
  41.         
  42.              ->        points to
  43.              LSBit     least significant bit
  44.              MSBit     most significant bit
  45.              LSByte    least significant byte
  46.              MSByte    most significant byte
  47.         
  48.         There  are several error codes that may be returned by  functions 
  49.         described in this document.  They are listed below:
  50.         
  51.              NO_ERROR                  0
  52.              ILLEGAL_COM_PORT         -1
  53.              INPUT_QUEUE_EMPTY        -2
  54.              OUTPUT_QUEUE_FULL        -3
  55.              ERROR_BAUD_RATE          -4
  56.              ERR_HSK_IN_PLACE         -6
  57.              ERR_BAD_DATA             -7
  58.              ERR_CARRIER_DROPPED      -8
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.         
  66.         Global Variables
  67.         --------------------------------------------------------
  68.         
  69.         There are a few global variables that may be viewed or altered by 
  70.         the application.  Because the serial ports are interrupt  driven, 
  71.         any accesses made with a variable that is above 16-bits should be 
  72.         made only while interrupts are disabled.
  73.         
  74.         
  75.         us _Com_Cprint_Output
  76.         
  77.         This  is  a bit field that determines the device that  the  bytes 
  78.         that are sent out through cprint().  If bit 0 is set,  characters 
  79.         will be sent to the display console.  If bit 1 is set, the  char-
  80.         acters are sent to the COM number held in _Cprint_Cn.  Any combi-
  81.         nation of these bits may be set or cleared.
  82.         
  83.         
  84.         us _Com_Error_Count[]
  85.         
  86.         This  is  an array that contains the number of  error  conditions 
  87.         that have happened for each of the COM ports.
  88.         
  89.         
  90.         ul _Com_Total_In
  91.         
  92.         This  contains the total number of bytes that have been  received 
  93.         from all the COM ports combined.
  94.         
  95.         
  96.         ul _Com_Total_Out
  97.         
  98.         This  contains the total number of bytes that have been sent  out 
  99.         all the COM ports combined.
  100.         
  101.         
  102.         us Com_Xfer_Timeout
  103.         
  104.         Default number of system ticks between sequential transmitted  or 
  105.         received  characters before modem style functions  (ie  cprint()) 
  106.         return a timeout error.
  107.         
  108.         
  109.         us _Cprint_Cn
  110.         
  111.         This is the COM number that cprint() uses to communicate through.
  112.         
  113.         
  114.         us _Xon_Percent
  115.         
  116.         This  is  the  percentage of the input buffer that  can  be  full 
  117.         before the ISR sends an XON to the remote.
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.         
  125.         Global Variables   (cont.)
  126.         --------------------------------------------------------
  127.         
  128.         us _Xoff_Percent
  129.         
  130.         This is the percentage of the input buffer that can be full  when 
  131.         the ISR sends an XOFF to the remote.
  132.         
  133.         
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.         
  141.         com_assert_dtr 
  142.         --------------------------------------------------------
  143.         
  144.         
  145.              Summary
  146.         
  147.              #include <int_14.h>
  148.         
  149.              short com_assert_dtr( cn );
  150.              us cn;         The COM port to initialize 
  151.         
  152.         
  153.         
  154.              Description
  155.         
  156.              This function asserts the data terminal ready signal ( DTR ) 
  157.              on the specified COM port cn. Asserting this signal  usually 
  158.              informs  a modem that the computer is powered up  and  ready 
  159.              for communications.
  160.         
  161.         
  162.         
  163.              Return Value
  164.         
  165.              The function returns a zero if completed, else the appropri-
  166.              ate error code is returned
  167.         
  168.         
  169.              See Also
  170.         
  171.              com_drop_dtr
  172.               
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.         
  180.         com_assert_rts 
  181.         --------------------------------------------------------
  182.         
  183.         
  184.              Summary
  185.         
  186.              #include <int_14.h>
  187.         
  188.              short com_assert_rts( cn );
  189.              us cn;         The COM port to initialize 
  190.         
  191.         
  192.         
  193.              Description
  194.         
  195.              This  function  asserts the request to send ( RTS )  on  the 
  196.              specified COM port cn. Asserting this signal may inform  the 
  197.              modem or other system that you want to send data.  In  hard-
  198.              ware handshaking, asserting this signal is used to tell  the 
  199.              sending system to send data.
  200.         
  201.         
  202.         
  203.              Return Value
  204.         
  205.              The function returns a zero if completed, else the appropri-
  206.              ate error code is returned
  207.         
  208.         
  209.              See Also
  210.         
  211.              com_drop_dtr
  212.               
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.         
  220.         com_clear_input     
  221.         ----------------------------------------------------------------
  222.         
  223.         
  224.              Summary
  225.              
  226.              #include <int_14.h>
  227.         
  228.              short com_clear_input( cn );
  229.              us cn;              The COM port to initialize 
  230.         
  231.         
  232.         
  233.              Description
  234.         
  235.              This  function  clears the input buffer that  is  associated 
  236.              with the COM port cn.  The input buffer holds the bytes that 
  237.              are received by the port but have not yet been retrieved  by 
  238.              the  input routines.  Clearing this buffer will destroy  any 
  239.              data that has been received and not retrieved.
  240.         
  241.         
  242.         
  243.              Return Value
  244.         
  245.              This  routine returns a zero if all went OK, else a  comple-
  246.              tion code will be returned explaining the error.
  247.         
  248.         
  249.         
  250.              See Also
  251.         
  252.              com_clear_output
  253.               
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.         
  261.         com_clear_output    
  262.         ----------------------------------------------------------------
  263.         
  264.         
  265.              Summary
  266.         
  267.              #include <int_14.h>
  268.         
  269.              short com_clear_output( cn );
  270.              us cn;              The COM port to initialize 
  271.         
  272.         
  273.         
  274.              Description
  275.         
  276.              This  function clears